﻿using System;
using System.IO;

namespace SfsTools.Core
{
    /// <summary>
    /// Interface for accessing a volume as a continuous stream of bytes.
    /// </summary>
    public interface IVolume : IDisposable
    {
        /// <summary>
        /// Gets the length of the volume, in bytes.
        /// </summary>
        /// <exception cref="NotSupportedException">An attempt was made to query the size of the volume on a volume which does not support this operation.</exception>
        Int64 Length
        {
            get;
        }

        /// <summary>
        /// Reads <paramref name="count"/> bytes from the volume.
        /// </summary>
        /// <param name="offset">The byte offset to start reading from.</param>
        /// <param name="count">The count of bytes read.</param>
        /// <returns>An array contaning the bytes read.</returns>
        /// <exception cref="EndOfStreamException">There is not enough space to read all the bytes (more bytes requested than the volume contains).</exception>
        /// <exception cref="ArgumentOutOfRangeException">The argument <paramref name="count"/> is out of valid range.</exception>
        /// <exception cref="IOException">An I/O error occurred.</exception>
        byte[] Read(Int64 offset, Int32 count);

        /// <summary>
        /// Writes the contents of <paramref name="buffer"/> to the volume.
        /// </summary>
        /// <param name="offset">The byte offset to start writing at.</param>
        /// <param name="buffer">The array containing the bytes to write.</param>
        /// <exception cref="EndOfStreamException">There is not enough space to write all the bytes.</exception>
        /// <exception cref="ArgumentNullException">The argument <paramref name="buffer"/> is <see langword="null"/>.</exception>
        /// <exception cref="IOException">An I/O error occurred.</exception>
        void Write(Int64 offset, byte[] buffer);

        /// <summary>
        /// Writes the contents of <paramref name="buffer"/> to the volume.
        /// </summary>
        /// <param name="offset">The byte offset to start writing at.</param>
        /// <param name="buffer">The array containing the bytes to write.</param>
        /// <param name="index">The index into <paramref name="buffer"/> to copy the bytes from.</param>
        /// <param name="count">The count of bytes to copy.</param>
        /// <exception cref="EndOfStreamException">There is not enough space to write all the bytes.</exception>
        /// <exception cref="ArgumentNullException">The argument <paramref name="buffer"/> is <see langword="null"/>.</exception>
        /// <exception cref="IOException">An I/O error occurred.</exception>
        void Write(Int64 offset, byte[] buffer, int index, int count);
    }
}
